LavaLauncher

LavaLauncher was a dock-like launcher panel for Wayland. I do not maintain LavaLauncher anymore. If you want to use if, I recommend using the lavalauncher-next branch, which contains improvements I have not merged into master by the time I stopped working on it.

It supports executing arbitrary commands on click, scroll and touch. My first Wayland project.

It should work with all Wayland servers that support the zwlr-layer-shell^↗ protocol.

You can find the code repository on sourcehut^↗.

lavalauncher(1)

lavalauncher(1) General Commands Manual lavalauncher(1)

NAME
LavaLauncher - A simple launcher panel for Wayland desktops

DESCRIPTION
LavaLauncher is a simple launcher panel for Wayland desktops.

It displays a dynamically sized bar with user defined buttons. These Buttons consist of an image,
which is displayed as the button icon on the bar, and at least one shell command, which is executed
when the user activates the button.

Buttons can be activated with pointer and touch events.

A single LavaLauncher instance can provide multiple such bars, across multiple outputs.

The Wayland compositor must implement the Layer-Shell and XDG-Output for LavaLauncher to work.

Beware: Unlike applications launchers which are similar in visual design to LavaLauncher, which are
often called "docks", LavaLauncher does not care about desktop files or icon themes nor does it
keep track running applications. Instead, LavaLaunchers approach of manually defined buttons is
considerably more flexible: You could have buttons not just for launching applications, but for
practically anything you could do in your shell, like for ejecting your optical drive, rotating
your screen, sending your cat an email, playing a funny sound, muting all audio, toggling your
lamps and a lot more. Be creative!

OPTIONS
-c <path>, --config <path>
Path to the configuration file.

-h, --help
Display a helpful help message and exit.

-v, --verbose
Enable verbose output.

-V, --version
Show version.

CONFIGURATION
LavaLauncher is configured with a configuration file.

Unless the path to a configuration file has been specified, LavaLauncher tries to find a configura‐
tion file at, in descending priority, "./lavalauncher.conf", "$XDG_CON‐
FIG_HOME/lavalauncher/lavalauncher.conf", "$HOME/.config/lavalauncher/lavalauncher.conf" "/usr/lo‐
cal/etc/lavalauncher/lavalauncher.conf" and "/etc/lavalauncher/lavalauncher.conf"

You can find an example configuration at the end of this section.

STRUCTURE
The configuration file has a simple structure. It consists of contexts and assignments.

Assignments are always inside context and have the following form.

<variable> = <value>;

Note that the value may be quoted, causing LavaLauncher to use it as is, including all whitespace
that would otherwise be stripped from the final string.

Contexts have the following form.

<context name>
{
<context content>
}

Some Contexts must be nested as contents of other contexts.

Comments start with an octothorpe ('#').

GLOBAL SETTINGS
Global settings can be configured in the "global-settings" context. The assignments which can be
made in this context are as follows.

watch-config-file
Automatically reload when a change in the configuration file is detected. Can be "true" or
"false". The default is "false". Behold: If the configuration file contains an error upon re‐
load, LavaLauncher will exit.

BAR
Every "bar" context will add a bar. The configuration changes in this context make up the default
configuration set of the bar. The assignments possible in this context are as follows.

alignment
Alignment of the buttons / bar. Can be "start", "center" or "end". The default is "center".

background-colour
The background colour of the bar. The default is "#000000".

border-colour
The border colour of the bar. The default is "#ffffff".

border
The border size. Expects either one integer, to set the size of all borders, or four integers,
to set the individual sizes for the top, left, right and bottom border. The default border size
is 1.

condition-resolution
The resolution proportions an output must have for the bar to be displayed on it. Can be either
"all", "wider-than-high" or "higher-than-wide". The default is "all".

condition-scale
The scale an output must have for the bar to be displayed on it. Can be either an integer
greater than zero or "all". The default is "all".

condition-transform
The rotation an output must have for the bar to be displayed on it. Can be "all", 0, 1, 2 or 3.
The numerical values represent rotations of 0, 90, 180 and 270 degrees, with the exact corre‐
spondence depending on the compositor. The default is "all".

cursor-name
Name of the cursor displayed when hovering the pointer over the bar. The default cursor is
"pointer". Behold: What cursors are available depends on your cursor theme.

exclusive-zone
Exclusive zone of the surface. Can be "true", "false" or "stationary". If "true", the composi‐
tor is informed that it should not obstruct the surface of LavaLauncher with other surfaces. If
"false", the compositor is informed that it can place other surfaces over or under the surface
of LavaLauncher. If "stationary", the compositor is informed that the surface of LavaLauncher
should not be moved to accommodate other Layer-Shell surfaces and that it can freely place
other surfaces over or under the surface of LavaLauncher. The default is "true". The exact im‐
plementation is compositor dependant; A compositor may choose to ignore the requested exclusive
zone of surfaces.

hidden-mode
Hidden mode of the bar. Can be "never", "always" and "river-auto". Defaults to "never".

In "never" mode, the bar is never hidden.

In "always" mode, the bar is always hidden.

The "river-auto" mode works only in the river Wayland compositor. In this mode, the bar is only
hidden if the output is currently occupied.

Behold: If you want a hidden bar which sits above windows on hover, you need to set the layer
to "top" and the exclusive zone to "off" or "stationary".

hidden-size
Size of the invisible area where hovering with a pointer will unhide the bar if it is hidden.
Defaults to 10.

icon-padding
Padding around the icons. The default 4.

indicator-active-colour
The colour of the indicator for icons being activated. The default is "#606060".

indicator-hover-colour
The colour of the indicator for icons over which the cursor hovers. The default is "#404040".

indicator-padding
Padding around the icon indicator. The default 0.

indicator-style
Style of the icon indicator. Can be "rectangle", "rounded-rectangle" and "circle". The default
is "rounded-rectangle". The corner radii for "rounded-rectangle" are the same as the ones of
the bar itself.

layer
Layer of the bar surface. Can be "overlay", "top", "bottom" or "background". Typically, "bot‐
tom" and "background" will be underneath regular windows, while "top" and "overlay" will be
above them, however the exact placement on the z axis depends on the implementation of the com‐
positor. The default layer is "bottom".

margin
The margin of the surface. Expects either one integer, to set the margin in all directions, or
four integers, to set the individual top-, left-, right- and bottom-margins. The default margin
is 0.

mode
The display mode of the bar. Can be "default", "full" or "aggressive".

In "default" mode, the bar is sized just large enough to house all the buttons. In this mode,
compositors may not respect margins parallel to the bar or the exclusive zone, possibly even
depending on the alignment. This is not a bug in LavaLauncher but a limitation of your composi‐
tor.

In "full" mode, the bar spans the entire length of the edge it is docked to.

The "aggressive" mode is visually identical to "normal" mode, however the surface of the bar is
sized and anchored more aggressively. This mode is intended for compositors with faulty Layer-
Shell implementations. If LavaLauncher is not placed at the desired location or the exclusive
zone or margins parallel to the bar are ignored, this mode may help. Beware however that it al‐
lows the compositor a lot less leeway when geometrically fitting the bar onto the screen.

namespace
The namespace of the Layer-Shell surface of the bar. Some compositors may treat Layer-Shell
surfaces differently based on their namespace. The default is "lhp.LavaLauncher". Note that
this option only takes effect once on bar creation.

output
Name of the output on which the bar should be displayed. Output names are compositor dependant.
If set to "all" or "*", LavaLauncher will display the bar on all outputs, which is the default
behaviour.

position
Position of the bar. Can be "top", "right", "bottom", "left". The bar will dock to that edge of
the output(s). The default position is "bottom".

radius
The radius of the corners. Expects either one integer, to set the radius of all corners, or
four integers, to set the individual radii for the top-left, top-right, bottom-left and bottom-
right corner. The default radius is 5. Set to 0 to disable corner roundness.

size
Size of the bar. The default size is 60.

CONFIG
Every "config" context will add an additional configuration set to a bar. As such, this context is
a nested inside the "bar" context. It copies the values of the default configuration set, but every
setting can be overridden. This is useful to change bar configuration based on conditionals, as
LavaLauncher will automatically choose the first configuration set with fitting conditions. Differ‐
ent instances of the same bar on different outputs can use different configuration sets, but a bar
has at most one instance per output and uses exactly one configuration set per instance. The as‐
signments possible in this context are the same as for the "bar" context.

BUTTON
Every "button" context will add a button to a bar. As such, this context is a nested inside the
"bar" context. The assignments possible in this context are as follows.

command
Sets the shell command for left-, right-, middle-click and touch interactions.

command[<bind>]
Bind a shell command to a specific interaction plus modifier combination. This combination is
defined by <bind>, which is a string containing an interaction name as well as optionally one
or multiple modifier names, separated by "+".

The possible interaction types are the following.

• mouse-{left, right, middle}
• mouse-{forward, backward}
• mouse-{mouse, side, extra, task, misc}
• mouse-{1 - 9}
• scroll-{up, down}
• touch

The possible modifiers are the following.

• alt
• capslock
• control
• logo (super)
• numlock
• shift

Behold: Due to the way the Layer-Shells keyboard interactivity was designed, LavaLauncher may
only get send an updated modifier state when it gains keyboard focus. In some compositors this
requires you to click on it, meaning that touch and scroll interactions with modifiers may not
work in some compositors. This is a bug in the Layer-Shell protocol, not in LavaLauncher.

image-path
The path to an image file, which will be used as the icon of the button.

SPACER
Every "spacer" context will add a spacer to a bar. As such, this context is a nested inside the
"bar" context. The assignments possible in this context are as follows.

length
Length of the spacer.

COMMANDS
Commands are executed using sh(1).

LavaLauncher understands typical backslash escape sequences.

LavaLauncher sets some environmental variables for the processes it launches. Since all commands
are executed via a shell, they can be used as arguments for the commands. These variables are as
follows.

$LAVALAUNCHER_OUTPUT_NAME
The name of the output the button has been clicked on.

$LAVALAUNCHER_OUTPUT_SCALE
The scale of the output the button has been clicked on.

COLOURS
LavaLauncher can parse hex code colours and read RGB values directly.

The supported formats are "#RRGGBB", "#RRGGBBAA", "0xRRGGBB" and "0xRRGGBBAA" for hex code colours
and "rgb(rrr,ggg,bbb)" and "rgba(rrr,ggg,bbb,aaa)" for RGB colours.

CONDITIONS
Conditions are (re-)evaluated and bars created and destroyed and their active configuration set
chosen accordingly whenever an outputs parameters are updated.

IMAGES
LavaLauncher support PNG images and, if enabled at compile time, SVG images. It is recommended to
use square images.

EXAMPLE CONFIGURATION
This is a simple configuration example, demonstrating a bar with two buttons and an additional con‐
figuration set. The second button uses advanced command binds.

global-settings
{
watch-config-file = true;
}

bar
{
output = eDP-1;
position = bottom;
background-colour = "#202020";

# Condition for the default configuration set.
condition-resolution = wider-than-high;

config
{
# Condition for this configuration set.
condition-resolution = higher-than-wide;

# Additional configuration sets copy the default configuration set,
# but settings can be overwritten.
position = left;
}

button
{
image-path = /path/to/image.png;
command = useful-script.sh;
}

button
{
image-path = /path/to/another/image.png;

command[mouse-left] = another-useful-script.sh;
command[mouse-right] = another-useful-script.sh;

command[shift+mouse-left] = another-useful-script.sh;
command[shift+alt+mouse-left] = another-useful-script.sh;

# Binding commands to scroll events is nice to configure
# things like audio volume or screen brightness
command[scroll-up] = volume up;
command[scroll-down] = volume down;
command[shift+scroll-up] = volume microphone-up;
command[shift+scroll-down] = volume microphone-down;
}
}

BUGS
Probably.

Please report all bugs you find with an explanation how to reproduce them.

MAILINGLIST
You can send bug reports, patches and feedback to the mailinglist.

<~leon_plickat/lavalauncher@lists.sr.ht>

GIT
This project is developed using git. You can find the repository by visiting the following URL.

<https://git.sr.ht/~leon_plickat/lavalauncher>

AUTHORS
Leon Henrik Plickat <leonhenrik.plickat@stud.uni-goettingen.de>

2026-03-17 lavalauncher(1)